For the past year and a half, I have been experimenting with my digital note-taking setup, ranging from live typesetting LaTeX to Apple Notes. I don’t think I can find a perfect solution that meets all my needs. But I think we can get close. I plan to make a bigger post describing my setup in more detail (in a similar fashion to castel.dev), but one of the main components is what we discuss here: how to use VS Code to incorporate images into your Markdown documents. We use Markdown because it supports things like embedded LaTeX math and code fences (such features are pivotal when taking technical notes during class).
The standard workflow
Incorporating images is a necessary function to have when typing notes, live, during lecture. And not only that, we need to do this fast. This is problematic in plain markdown because it requires us to…
- Download the image file and save it to some path
- Specify the path relative to your document like so:
in the document itself.
In some ways, you’d be done there. But… most figures are quite large and take up majority of the page…
no good! And guess what? There is no standard way to resize images in markdown! So you’d have to specify an HTML element like so:
<img src="http://www.fillmurray.com/460/300">From here, you could in theory add image alignment and sizing, but this still takes another ~45 seconds:
<p align="center">
<img alt="picture 1" src="http://www.fillmurray.com/460/300" width="350" />
</p>In all, this whole process probably takes ~2 minutes per image. And if you are typing live during a lecture, you’ll quickly be lost in the content and won’t be able to keep up with the lecturer. For these reasons, after playing around with various ideas, I describe a new workflow below.
A new, efficient workflow
First of all, this workflow is powered by:
- VS Code (necessary to use due to the use of the extension listed below)
- Markdown Image VS Code extension by Hancel.Lin (link)
The main philosophy:
- We want to upload the images on a remote server and retrieve a URL in return. We will use this as the path since it eliminates the need to download, save, and specify the path locally.
- We use a public Github repo to upload the images to automatically. This allows us to store our images on Github’s servers and retrieve a URL on the internet.
- Note: You can also use this setup with some other CDN delivery network that the Markdown Image extension allows for (such as Cloudflare). But I personally think Github is the safest and best option.
- We use a public Github repo to upload the images to automatically. This allows us to store our images on Github’s servers and retrieve a URL on the internet.
Setup
- Make a new Github repo to store the images.
- Open up the config settings for the above extension in VS Code. Specify the following fields based on your account info and repo:
- branch
- path (i.e., the folder inside your GH repo where you want to store the images)
- repository name
- token (your personal access token)
- Now change the base upload method field to ‘Github’ in the extension settings.
- (Optional) while you are at it, you can also change the base image width in the extension settings, the code type (I prefer the HTML string over raw Markdown since it renders nicely in Github’s web interface), the max image width (I use 300-400).
- (Optional) if you want center-alignment, make a VS Code snippet with the following code:
<p align="center">
</p>and then paste your image in between the element block dividers.
And that’s it! All you need to do is copy an image to your clipboard (i.e., from a screenshot) and paste it in using the extension by right-clicking and select (if enabled and there is other extensions overwriting the command):
done! Now your image uploading should take about ~5 seconds (a much better improvement from ~2 minutes!).